//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IRelationsPopulateHelper.cs
//
//  Description: Interface that is implemented to control relations.
// 
//--------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text;
using Chili.Opf3.Relations;

namespace Chili.Opf3
{
	/// <summary>
	/// Interface that is implemented to control the way how relations are loaded.
	/// </summary>
	/// <remarks>
	/// 	<para>This interface is implemented by classes that won't let the framework
	///     automatically populate the relations with data.</para>
	/// 	<para>If the framework encounters a persistent object that implements this
	///     interface it asks the persistent if to populate it. The persistent returns whether
	///		to do it on its own or to let the framework populate it. If the interface loads
	///		the related data a second method is invoked to do the loading.</para>
	/// </remarks>
	/// <example>
	///     The following example shows how to implement the interface. In the following example
	///		all the related properties aren't populate.
	///     <code lang="CS">
	/// [Persistent("USER")]
	/// public class User : IRelationsPopulateHelper
	/// {
	///	   // ... Other properties and code.
	///		
	///    bool IRelationsPopulateHelper.RelationIsHandled(string relationName, RelationInformation info)
	///    {
	///        // Return true for all relations. Means all are handled by this interface.
	///        return true;
	///    }
	///
	///    object IRelationsPopulateHelper.GetRelatedObject(string relationName, RelationInformation info)
	///    {
	///       // Return null for all relations. No related object is going to be populated.
	///       return null;
	///    }
	/// }
	///     </code>
	/// </example>
	public interface IRelationsPopulateHelper
	{
		/// <summary>
		/// Returns whether the relation is handled by the interface.
		/// </summary>
		/// <param name="relationName">The name of the relation that is checked for being handled.</param>
		/// <param name="info">An instance of the <see cref="RelationInformation">RelationInformation</see> object
		/// that holds the most important information for the relation.</param>
		/// <returns>True if the relation is handled by the interface; otherwise false.</returns>
		bool RelationIsHandled(string relationName, RelationInformation info);

		/// <summary>
		/// Returns the related object for the relation.
		/// </summary>
		/// <remarks>
		/// This method loads the related object(s) and returns it/them. If the relation would return an 
		/// <see cref="ObjectSet{T}">ObjectSet</see> (see <see cref="ObjectSetHolder{T}">ObjectSetHolder</see>) this 
		/// method needs to return an ObjectSet; the  same applies to List&lt;T&gt; (see 
		/// <see cref="ObjectListHolder{T}">ObjectListHolder</see>) and a single persistent 
		/// (see <see cref="ObjectHolder{T}">ObjectHolder</see>). Otherwise a runtime error is going to be thrown.		
		/// </remarks>
		/// <param name="relationName">The name of the relation.</param>
		/// <param name="info">An instance of the <see cref="RelationInformation">RelationInformation</see> object
		/// that holds the most important information for the relation.</param>
		/// <returns>The related object(s) or null if nothing should be returned.</returns>
		object GetRelatedObject(string relationName, RelationInformation info);
	}
}
